EPFO Latest Employment - Mobile

The following document highlights the details of the EPFO Latest Employment - Mobile API.

API Description

Objective

The EPFO Latest Employment - Mobile API retrieves the Universal Account Number(UAN) and the latest employment details associated with a mobile number from the Employees' Provident Fund Organisation (EPFO) records.

Input	Output
Mobile number and consent	The UAN and the latest employment details including name, establishment name, member ID, date of joining, and date of exit. The complete list of output fields is available in the Success Response Details section

API URL

https://ind-engine.thomas.hyperverge.co/v1/fetchEpfoLatest

API Endpoint

fetchEpfoLatest

Overview

The EPFO Latest Employment - Mobile API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should send all data in JSON format through a POST request.

Method - POST

Authentication

You need a unique pair of application ID ( appId ) and application key ( appKey ) from HyperVerge to verify your identity for accessing the API.

Headers

Header	Mandatory / Optional	Description	Input Format
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
transactionId	Mandatory	A unique identifier for tracking a user journey	This should be both unique and easily associated with the user's journey in your application(s)

Inputs

The following table provides the details of the parameters required for the EPFO Latest Employment - Mobile API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
mobileNumber	Mandatory	string	The 10-digit mobile number associated with the EPFO account	10-digit mobile number	Not Applicable
consent	Mandatory	string	The consent provided by the user for accessing EPFO data	"Y" or "N"	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the EPFO Latest Employment - Mobile API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/fetchEpfoLatest' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "mobileNumber": "<Enter_the_Mobile_Number>",
    "consent": "<Enter_Y_or_N>"
}'

Success Responses

The following code snippet demonstrates a success response from the EPFO Latest Employment - Mobile API:

{
  "status": "success",
  "statusCode": 200,
  "result": {
    "message": "UAN fetched from mobile.",
    "uanList": [
      "<UAN_Number>"
    ],
    "employmentData": {
      "name": "<Employee_Name>",
      "establishmentName": "<Establishment_Name>",
      "memberId": "<Member_ID>",
      "dateOfJoining": "<Date_Of_Joining>",
      "dateOfExit": "<Date_Of_Exit>"
    }
  },
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Success Response Details

The following table outlines the details of the success response from the EPFO Latest Employment - Mobile API:

Parameter	Type	Description
status	string	The status of the request
statusCode	integer	The status code of the response
result	object	The result object containing the UAN list and employment data
result.message	string	The message indicating the status of the UAN fetch operation
result.uanList	array	The Universal Account Numbers (UAN) retrieved from the mobile number
result.employmentData	object	The employment details object containing all employment information
result.employmentData.name	string	The full name of the individual
result.employmentData.establishmentName	string	The name of the company or organization where the individual was employed
result.employmentData.memberId	string	The unique identification number assigned to the individual within the organization or employment system
result.employmentData.dateOfJoining	string	The date when the individual started working at the establishment
result.employmentData.dateOfExit	string	The date when the individual ceased employment with the establishment, either through resignation, termination, or any other reason
metaData	object	The metadata object containing request tracking information
metaData.requestId	string	The unique identifier for the request
metaData.transactionId	string	The transaction identifier for tracking

Failure Response

The following code snippet demonstrates a response when no UANs are found for the provided mobile number:

{
  "status": "success",
  "statusCode": 200,
  "result": {
    "message": "Provided mobile number doesn't have any UAN."
  },
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Error Responses

The following are some error responses from the EPFO Latest Employment - Mobile API:

Invalid Mobile Number

{
  "message": "Provide a valid mobile number",
  "statusCode": 400,
  "status": "failure",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Input Validation Error

{
  "message": "Input Validation Error: does not meet minimum length of 10",
  "statusCode": 400,
  "status": "failure"
}

No Consent Given

{
  "message": "Please provide consent",
  "statusCode": 400,
  "status": "failure",
  "metaData": {
    "requestId": "<Request_ID>",
    "transactionId": "<Transaction_ID>"
  }
}

Missing/Invalid Credentials

{
  "message": "Missing/Invalid credentials",
  "statusCode": 401,
  "status": "failure"
}

Internal Server Error

{
  "message": "Internal Server Error",
  "statusCode": 500,
  "status": "failure"
}

Service Unavailable

{
  "message": "Service Unavailable",
  "statusCode": 503,
  "status": "failure"
}

Error Response Details

A failure or error response contains a failure status with a relevant status code and error message.
The following table lists all error responses:

Status Code	Error Message	Error Description	Error Resolution
400	Provide a valid mobile number	The request has an invalid mobile number that contains special characters or is not properly formatted	Provide a valid 10-digit mobile number without special characters
400	Input Validation Error: does not meet minimum length of 10	The request has a mobile number that is less than or greater than 10 digits	Provide a valid 10-digit mobile number
400	Please provide consent	The request is missing the consent parameter or has an invalid consent value	Provide valid consent parameter with value "Y" or "N" in the request
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values	Provide valid appId and appKey credentials in the request
500	Internal Server Error	The request has an internal server error. Please check the request headers or contact the HyperVerge team for investigation	Please check the request headers or contact the HyperVerge team for resolution
503	Service Unavailable	The EPFO service is currently unavailable. Please try again later or contact the HyperVerge team for investigation	Please try again later or contact the HyperVerge team for resolution